package com.googlecode.yoohoo.xmppcore.stanza;

import com.googlecode.yoohoo.xmppcore.connection.IConnectionContext;
import com.googlecode.yoohoo.xmppcore.protocol.XmppProtocolException;
import com.googlecode.yoohoo.xmppcore.protocol.stanza.Iq;
import com.googlecode.yoohoo.xmppcore.protocol.stanza.Stanza;

/**
 * XMPP Stanza handler.
 *
 */
public interface IStanzaHandler<K extends IConnectionContext, T extends Stanza> {
	public static final String KEY_STANZA_HANDLER_TYPE = "__yoohoo.k.s.h.t__"; // YooHoo key stanza handler type
	/**
	 * 
	 * @param context Context of current connection.
	 * @param stanza Stanza that will be processed
	 * @return Return <tt>true</tt> if IQ processing is complete, handler will call {@link #complete(IXmppContext, Iq)}.
	 */
	boolean process(K context, T stanza);
	
	/**
	 * Will be called when stanza processing complete.
	 * @param context Context of current connection.
	 * @param stanza Stanza that will be processed.
	 */
	void complete(K context, T stanza);
	
	/**
	 * Save intermediate states of processing.
	 * @param context Context of current connection.
	 * @param stanza Stanza that will be processed.
	 */
	void saveStates(K context, T stanza);
	
	/**
	 * Will be called when an exception was thrown by {@link #process(IConnectionContext, Stanza)}.
	 * @param context Context of current connection.
	 * @param stanza Stanza that will be processed.
	 * @param e Exception was thrown.
	 */
	void exceptionThrew(K context, T stanza, XmppProtocolException e);
	
	/**
	 * Restore intermediate states of processing.
	 * @param context Context of current connection.
	 * @param stanza Stanza that will be processed.
	 */
	void restoreStates(K context, T stanza);
}
